//*********************************************************
//
//    Copyright (c) Microsoft. All rights reserved.
//    This code is licensed under the Apache License, Version 2.0.
//    THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF
//    ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY
//    IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR
//    PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.
//
//*********************************************************

namespace Microsoft.Research.DataLayer
{
    /// <summary>
    /// Data providers are responsible for certain kind of resources. And they 
    /// should be state-less. All the parameters should be passed to them
    /// before invoking them to retrieve data.
    /// </summary>
    public interface IDataProvider
    {
        /// <summary>
        /// Gets or sets the Name of the data provider.
        /// </summary>
        /// <value>The name.</value>
        string Name { get; set; }

        /// <summary>
        /// Provider gets a chance to initialize itself before being asked 
        /// to process any requests. This should be called by the one who 
        /// instantiates this object. 
        /// </summary>
        void Initialize();

        /// <summary>
        /// Provider gets a chance to initialize the configurators.
        /// This might be required if the UI and the provider might have to be initialized seperately.
        /// </summary>
        void InitializeConfigurator();

        /// <summary>
        /// Store the data inside DataObject and return a version number for that. 
        /// Caution : When you consume the data inside the Steam object, one might not
        /// be able to access them once again. So when you consume the data to store it
        /// make sure to add it back. 
        /// </summary>
        /// <param name="parameters">Parameters to use to access the version controled data storage</param>
        /// <param name="dataObject">Real data to be stored is encapsulated within this. This should also contain
        /// a name for this data in the Name field</param>
        /// <returns>a unique identifier that can be used to retrieve the same data at a later time</returns>
        string Store(string parameters, DataObject dataObject);


        /// <summary>
        /// Store the data inside DataObject and return a version number for that.
        /// Caution : When you consume the data inside the Steam object, one might not
        /// be able to access them once again. So when you consume the data to store it
        /// make sure to add it back.
        /// </summary>
        /// <param name="parameters">Parameters to use to access the version controled data storage</param>
        /// <param name="key">The key which the provider has to use save the data.</param>
        /// <param name="dataObject">Real data to be stored is encapsulated within this. This should also contain
        /// a name for this data in the Name field</param>
        /// <returns>
        /// a unique identifier that can be used to retrieve the same data at a later time
        /// </returns>
        string Store(string parameters, string key, DataObject dataObject);


        /// <summary>
        /// Retrieve the stored data associated with the given unique key.
        /// </summary>
        /// <param name="parameters">Parameters to use to access the data storage.</param>
        /// <param name="key">Unique identifier of the data to be retrieved</param>
        /// <returns>Data associated with the unique key.</returns>
        DataObject Retrieve(string parameters, string key);

        /// <summary>
        /// Provide a way to get your parameters using WPF application.
        /// </summary>
        /// <returns></returns>
        IDataProviderConfiguratorWPF GetWPFConfigurator();

        /// <summary>
        /// Provide a way to get your parameters using Win32 application.
        /// </summary>
        /// <returns></returns>
        IDataProviderConfiguratorWinForms GetWinFormsConfigurator();
    }
}
